Install and setup

Spinal is a Scala library (a programming language using the Java VM) so it requires setting up a Scala environment; there are many ways to do so. Also, it generates VHDL, Verilog or SystemVerilog, which can be used by many different tools. This section describes the supported way to install a SpinalHDL description to Simulation flow, but there can be many variations.

Required/Recommended tools

Before you download the SpinalHDL tools, you need to install a Scala environment:

Java JDK, a Java environment
Scala 2, compiler and library
SBT, a Scala build tool

These tools enable to use Spinal; but without any other tools, it is limited to HDL code generation.

To enable more features we recommend:

An IDE (for instance the currently recommended IntelliJ with its Scala plugin or VSCodium with Metals extension) to get features such as:
- Code suggestions / completion
- Automatic build with syntax errors right in the code
- Generate code with a single click
- Run simulation / tests with a single click (if a supported simulator is set up)
A supported simulator like Verilator to test the design right from SpinalHDL.
Gtkwave to view the waves generated by Verilator during simulation.
Git for version control system
A C++ toolchain, needed for simulating with Verilator
A linux shell, needed for simulating with Verilator

Linux Installation

At time of writing the recommended way of installing Scala and SBT is via Coursier. Coursier is able to in addition to the scala tools install a Java JDK to use, in the example below we install Java from the package manager. We recommend to install JDK 17 (LTS) because of compatibility with the used Scala version.

For Debian or Ubuntu we run:

sudo apt-get update
sudo apt-get install openjdk-17-jdk-headless curl git
curl -fL "https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-linux.gz" | gzip -d > cs
chmod +x cs
# should find the just installed jdk, agree to cs' questions for adding to your PATH
./cs setup
source ~/.profile

If you want to install the tools for simulation and/or formal proofs, we recommend oss-cad-suite. It contains a waveform viewer (gtkWave), verilog simulators (verilator and iverilog), VHDL simulator (GHDL) and other tools. In case you want to build the tools yourself have a look at the legacy simulation tool installation instructions.

We first install the needed C++ toolchain and download oss-cad-suite. To use it we must load the oss-cad-suite environment for each shell we want to use it in. Note that oss-cad-suite contains a Python 3 interpreter that may interfere with the system Python installation if loaded permanently.

Go to the oss-cad-suite release page to get the download link for the latest version. You can download/extract oss-cad-suite to a folder of your choice. (last tested version of oss-cad-suite is 2023-10-22, but more recent ones will most likely also work)

sudo apt-get install make gcc g++ zlib1g-dev
curl -fLO <download link>
tar xzf <file that you downloaded>

To use oss-cad-suite in a shell you need to load it’s environment, e.g. via source <path to oss-cad-suite>/environment.

Mac OS X Installation

You can use homebrew to install on Mac OS X. By default homebrew installs Java 21, but the SpinalHDL tutorial SpinalTemplateSbt uses Scala version 2.12.16, which is not supported by Java 21 (17 is still the recommended LTS version, https://whichjdk.com/). So to install Java version 1.7 do:

brew install openjdk@17

And then add this to your path.

export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"

To manage multiple versions of Java it is also essential to have jenv installed.

brew install jenv

Jenv added these lines to my .bash_profile

export PATH="$HOME/.jenv/bin:$PATH"
eval "$(jenv init -)"

Next you have to install scala’s interactive build tool sbt.

brew install sbt

If this works for you, please let us know. If this does not work for you, you can read the github issue about Mac o SX installation here. https://github.com/SpinalHDL/SpinalHDL/issues/1216

If you want to install the tools for simulation and/or formal proofs, we recommend oss-cad-suite.

Windows installation

Note

While a native installation is possible the simpler and currently recommended way is to use WSL on Windows. If you want to use WSL, install it, a distribution of your choice and follow the Linux installation instructions. Data in your WSL instance can be accessed from windows under \\wsl$. In case you want to use IntelliJ you’ll have to download the Linux version to WSL, if you want to use VSCode then the Windows version can be used to remotely edit in WSL.

At time of writing the recommended way of installing Scala and SBT is via Coursier. Coursier is able to in addition to the scala tools install a Java JDK to use, in the example below we install Java manually. We recommend to install JDK 17 (LTS) because of compatibility with Scala.

First download and install Adoptium JDK 17. Download, unzip and run the Coursier installer, when asked agree to an update of your PATH variable. Reboot to force an update of PATH.

This is sufficient for generating hardware. For simulation continue with either choice below. In case you want to build the tools yourself have a look at the legacy simulation tool installation instructions.

Note

An All-in-One solution offered by SpinalHDL maintainer Readon <https://github.com/Readon> is available to install and run SpinalHDL with Verilator simulation and formal verification via SymbiYosys. Download it and install the environment anywhere on your disk. Start the build environment by clicking on the MSYS2-MINGW64 icon in the Start menu and use the MSYS2 default console. An alternative is to use the Windows Terminal or a Tabby-like application and use the startup command %MSYS2_ROOT%\msys2_shell.cmd -defterm -here -no-start -mingw64, where the %MSYS2_ROOT% is the location of the msys2 installation. It is worth noting that if you want to use it offline, you should carefully select the libraries that the project depends on, otherwise you will need to download the packages manually. See the README for the repos for more details.

MSYS2 verilator for simulation

We recommend to install compiler/verilator through MSYS2 <https://www.msys2.org>. Other methods of installing gcc/make/shell (e.g. chocolatey, scoop, etc.) may also work but are untested.

SpinalHDL maintainer Readon <https://github.com/Readon> is maintaining a MSYS2 fork that default installs all needed officially available and custom built packages (also maintained by Readon here <https://github.com/Readon/MINGW-SpinalHDL>) for simulation and formal verification. It can be found here <https://github.com/Readon/msys2-installer>. If used then the packages installed below via pacman are already installed and those installation steps can be skipped.

Currently verilator 4.228 is latest available version known to work.

Download the latest installer and install MSYS2 with default settings. You should get a MSYS2 terminal at the end of the installation, there run:

pacman -Syuu
# will (request) close down terminal
# open 'MSYS2 MINGW64' from start menu
pacman -Syuu
pacman -S --needed base-devel mingw-w64-x86_64-toolchain mingw-w64-x86_64-iverilog mingw-w64-x86_64-ghdl-llvm git
curl -O https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-verilator-4.228-1-any.pkg.tar.zst
pacman -U mingw-w64-x86_64-verilator-4.228-1-any.pkg.tar.zst

In a MSYS2 MINGW64 terminal we need to set some environment variables to make Java/sbt available (you can make these settings persistent by adding them to ~/.bashrc in MSYS2):

export VERILATOR_ROOT=/mingw64/share/verilator/
export PATH=/c/Program\ Files/Eclipse\ Adoptium/jdk-17.0.8.101-hotspot/bin:$PATH
export PATH=/c/Users/User/AppData/Local/Coursier/data/bin:$PATH

With this you should be able to run sbt/verilator simulations from MSYS2 terminals (sbt via calling sbt.bat).

MSYS2 for formal verification

In addition to the steps above we also need to install yosys, sby, z3 and yices. Both yosys(yosys-smtbmc workable) and sby are not available as official MSYS2 packages, but packages are provided by Readon <https://github.com/Readon>. If you used their installer then these steps are not needed (you should check if there are newer packages available).

pacman -S mingw-w64-x86_64-z3 mingw-w64-x86_64-yices mingw-w64-x86_64-autotools mingw-w64-x86_64-python3-pip
python3 -m pip install click
curl -OL https://github.com/Readon/MINGW-SpinalHDL/releases/download/v0.4.9/mingw-w64-x86_64-yosys-0.31-1-any.pkg.tar.zst
curl -OL https://github.com/Readon/MINGW-SpinalHDL/releases/download/v0.4.9/mingw-w64-x86_64-python-sby-0.31-1-any.pkg.tar.zst
pacman -U *-yosys-*.pkg.tar.*
pacman -U *-python-sby-*.pkg.tar*

OCI Container

A container for SpinalHDL development is available as well. The container is hosted at ghcr.io/spinalhdl/docker:master and can be used with Docker/Podman/Github Codespaces. It is used for the SpinalHDL CI regression and can therefore be an easy way to run the CI commands locally.

To run the container run e.g. podman run -v .:/workspace -it ghcr.io/spinalhdl/docker:master in a SpinalHDL project root directory, making the project directory available in /workspace.

Please consult the documentation of you Distribution (Linux, WSL) or Docker (Windows) on how to install the container runtime you want to use. Multiple editors/IDEs (e.g. VSCode, IntelliJ, Neovide) allow for remote development in a container. Please consult the documentation of the editor on how to do remote development.

Installing SBT in an internet-free Linux environment

Note

If you are not using an air-gapped environment we recommend to go with the normal linux installation. (which is a subset of the installation for an air-gapped environment)

Normally, SBT uses online repositories to download and cache your projects dependencies. This cache is located in several folders:

~/.sbt
~/.cache/JNA
~/.cache/coursier

To set up an internet-free environment, you can:

Set up an environment with internet (see above)
Launch a Spinal command (see Using Spinal from CLI with SBT) to fetch dependencies (for instance using the getting started repository)
Copy the caches to the internet-free environment.

Create a first SpinalHDL project

We have prepared a ready-to-go project for you the: getting started repository.

You can download it, or clone it.

The following commands clone the project into a new directory named MySpinalProject and initialize a fresh git history:

git clone --depth 1 https://github.com/SpinalHDL/SpinalTemplateSbt.git MySpinalProject
cd MySpinalProject
rm -rf .git
git init
git add .
git commit -m "Initial commit from template"

The directory structure of a project

Note

The structure described here is the default structure, but it can be easily modified.

In the root of the project are the following files:

File	Description
`build.sbt`	Scala configuration for `sbt`
`build.sc`	Scala configuration for `mill`, an alternative to `sbt`
`hw/`	The folder containing hardware descriptions
`project/`	More Scala configuration
`README.md`	A `text/markdown` file describing your project
`.gitignore`	List of files to ignore in versioning
`.mill-version`	More configuration for `mill`
`.scalafmt.conf`	Configuration of rules to auto-format the code

As you probably guessed it, the interesting thing here is hw/. It contains four folders: spinal/, verilog/ and vhdl/ for your IPs and gen/ for IPs generated with Spinal.

hw/spinal/ contains a folder named after your project name. This name must be set in build.sbt (along with the company name) and in build.sc; and it must be the one in package yourprojectname at the beginning of .scala files.

In hw/spinal/yourprojectname/, are the descriptions of your IPs, simulation tests, formal tests; and there is Config.scala, which contains the configuration of Spinal.

Note

sbt must be used only at the root of the project, in the folder containing build.sbt.

Using Spinal on SpinalHDL code

Now the tutorial shows how to use Spinal on SpinalHDL code depending on your development environment: